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1 INTRODUCTION 


The following sections contain information on assembling, 
building and debugging an ICOPS application system. A knowlege of 
A System for Interconnected Processing by G. M. Stabler 
(particularly Chapter 3) and the Brown University Graphics System 
is assumed. 

Someday when the Language for Systems Development compiler is 
operational and supports code generation for both tne 360 and 
BUGS, ICOPS application procedures can be written in this higher 
level language. Until then applications must be written in an 
assembly language similar to M4A assembly language and assembled 
for both machines by using either a 360 or a BUGS macro library to 
generate code for the appropriate machine. 
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2 THE ICP ASSEMBLY LANGUAGE 


i 


The instruction set is close to that of a 360 and includes a 
complete set of logical, arithmetic, character handling, and 
testing and branching instructions. 

Note that instructions are based on 16 bit halfwords (i.e., a 
Load instruction assembled for the 360 generates a Load Halfword). 
Computations on both machines are done in halfword arithmetic 
(i.e., an Add instruction assembled for the 3b0 generates an Add 
Halfword). Unfortunately addresses are not the same length on both 
machines; an address is a fullword on the 360 and a halfword on 
BUGS. For this reason. Real Address instructions were defined 
which generate the appropriate address manipulation instructions 
on both machines. Also there is a special macro, SELECT, for 
generating a branch instruction from an index into a table of 
addresses. 

2. 1 INSTRUCTION SET 


Below 

comprising 


are given the instructions, mnemonics, and formats 
this instruction set. For more information on the 
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pcz.f- 

9 ct 


Cv/'tf 




$***• 


various instructions, refer to the M4A Principles of Operation 
manual. 


v ADD 

A 

R 1, D2 (X 2 , B2 ) 

✓ ADD HALFWORDS 

AH 

Dl (B1) , D2 (B2) 

/ ADD HEX DIGIT 

* AX 

R1,12 

•'ADD IMMEDIATE 

* AI 

RIS,RIF,IH2 

✓ ADD LOGICAL 

AL 

R1 , D2 (X 2 , B2) 

✓ ADD LOGICAL IMMEDIATE 

* ALI 

R1S,RIF,IH2 

✓ADD LOGICAL REGISTER 

ALR 

R1, R2 

*/ ADD REGISTER 

AR 

R 1, R 2 

✓ADD TO HALFWORD IMMEDIATE 

M AHI 

Dl (B1) ,12 

v/AlMD 

N 

R1,D2 (X2,B2) 

v/AND CHARACTERS 

NC 

Dl (L,B1) , D2 (B2) 

v/AND CHARACTERS LONG 

M NCL 

Dl {LR , B 1) ,D2(B2) 

1 / AND IMMEDIATE 

NI 

R1S,R1F,IH2 

v/AND REGISTER 

NR 

R 1, R2 

/AND TO BYTE IMMEDIATE 

* NBI 

Dl(B1),12 

/ BRANCH AND LINK 

BAL 

R1,D2 (X2,B2) 

✓'BRANCH AND LINK REGISTER 

BALR 

R 1, R2 

✓ BRANCH ON COUNT 

BCT 

R 1 , D2 (X 2) 

✓ BRANCH ON COUNT REGISTER 

BCTR 

R1,R2 

✓ BRANCH ON INDEX HIGH 

BXH 

R1 , R3 , D2 (X2 ) 

BRANCH ON INDEX LOW OR EQUAL 

BXLE 

R1,R3,D2 (X2) 

✓'COMPARE 

C 

R1,D2(X2,B2) 

✓COMPARE HALFWORD TO IMMEDIATE 

m CHI 

Dl(B1),12 

^COMPARE HALFWORDS 

CH 

Dl (B1) ,D2 (B2) 

✓COMPARE IMMEDIATE 

Cl 

R1F,IH2 

./COMPARE LOGICAL 

CL 

HI,D2 (X2,B2) 

✓COMPARE LOGICAL CHARACTERS 

CLC 

Dl ( L,B 1 ) , D2 ( B2) 

✓COMPARE LOGICAL CHARACTERS LONG 

* CLCL 

Dl ( LR , B 1 ) ,D 2(B2) 

/COMPARE LOGICAL HALFWORDS 

M CLH 

D 1 ( B1) , D2 (B 2) 

✓COMPARE LOGICAL IMMEDIATE 

CLI 

R1F,IH2 

✓ COMPARE LOGICAL REGISTER 

CLR 

R 1, R 2 

✓ COMPARE LOGICAL TO BYTE 

✓ CLB 

R1 , D2 (X 2, B2 ) 

✓COMPARE LOGICAL TO BYTE IMMEDIATE 

t*CLBI 

Dl ( B1 ) ,12 

✓ C COMPARE REAL ADDRESSES 

* CRA 

R 1,D2(X2,B2) 

✓ COMPARE REGISTER 

CR 

R 1 , R2 

(" CONVERT BINARY TO DECIMAL 

* CBD 

R1,D2(X2,B2) 

f CONVERT BINARY TO HEX 

*C BX 

R1,D2(X2,B2) 

i CONVERT DECIMAL TO BINARY 

T CDB 

R 1 , D2 (X 2 ,B2 ) 

i CONVERT HEX TO BINARY 

* CXB 

R1,D2(X2,B2) 

✓DIVIDE ** 

D 

R1 , D2 (X2 , B2) 

/DIVIDE HALFWORDS ** 

m DH 

Dl ( B 1 ) , D2 (B 2) 

✓DIVIDE IMMEDIATE ** 

* DI 

R IS ,R 1F,1I12 

✓ DIVIDE REGISTER ** 

DR 

R 1 , R2 

1 - EXCLUSIVE OR 

X 

R 1,D2(X2,B2) 

J EXCLUSIVE OR CHARACTERS 

XC 

Dl (L, B1) , D2 (B2) 
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✓EXCLUSIVE OR CHARACTERS LONG 

M XCL 

D1 (LR,B1) , D2 (B2) 

✓EXCLUSIVE OR IMMEDIATE 

XI 

R1S,R1F,IH2 

v/EXCLUS IVE OR REGISTER 

XR 

R1 ,R2 

“'EXCLUSIVE OR TO BYTE IMMEDIATE 

XBI 

D 1 (B1) ,12 

^EXECUTE 

EX 

R 1, D2(X2,B2) 

•'TILL 

» FILL 

D 1 (L,B1) ,D2 (B2) 

/FILL LONG 

*FILLL 

D 1 (LR , B 1) ,D2 (B2) 

FREE CONTROLLED STORAGE 

r FREE 

R1 , D2 (X 2 , B2 ) 

FREE CONTROLLED STORAGE REGISTER 

FREER 

R 1 ,R2 

GET CONTROLLED STORAGE 

* GET 

R 1, D2(X2,B2) 

GET CONTROLLED STORAGE REGISTER 

* GETR 

R 1 , R2 

•✓INSERT BYTE 

IB 

R 1, D2(X2,B2) 

✓ LOAD 

L 

R1 , D2 (X2,B2) 

✓"LOAD ADDRESS 

LA 

R 1, D2 (X2,B2) 

•'LOAD AND ZERO 

LZ 

R 1, D2(X2,B2) 

''LOAD BYTE 

^ LB 

HI , D2 (X2, B2) 

•/LOAD COMPLEMENT 

i- LC 

R1,D2(X2,B2) 

'LOAD COMPLEMENT REGISTER 

LCR 

R 1 , R2 

'LOAD DEFERRED 

LD 

R 1, D2 (X2,B2) 

'LOAD DEFERRED IMMEDIATE 

* LDI 

RIS,1A2 

''LOAD DEFERRED REGISTER 

LDR 

R 1 , R2 

•'LOAD HEX DIGIT 

rA LX 

R 1,12 

'LOAD IMMEDIATE 

* LI 

R1S ,1H2 

LOAD MULTIPLE PARAMETER ADDRESS * 

' LMPA 

R1,R3,N2,B2 

* j LOAD MULTIPLE REAL ADDRESSES 

L MR A 

R1,RJ,D2 (B2) 

lLOAD MULTIPLE REAL ADDRESSES DEFERRED LMRAD 

R1,R3,D2(B2) 

•'LOAD NEGATIVE 

w LN 

HI,D2 (X2,B2) 

'LOAD NEGATIVE REGISTER 

LNR 

R 1, R2 

* 1 LOAD PARAMETER ADDRESS * 

CLP A 

R1,N2 , B2 

-/ LOAD POSITIVE 

«LP 

R1,D2 (X2,B2) 

-LOAD POSITIVE REGISTER 

LPR 

HI , R2 

*[load real ADDRESS 

[LRA 

R 1, D2 (X 2 , B 2 ) 

✓ LOAD REGISTER 

LR 

R 1, R2 

•LOAD SIGNED BYTE 

LSB 

R 1 , D2 (X 2 , B2 ) 

'✓MOVE CHARACTERS 

M VC 

D 1 (L, B1) ,D2 (B2) 

''MOVE CHARACTERS LONG 

m MVCL 

D 1 ( LR , B 1) ,D2(B2) 

'■'MOVE CHARACTERS NON-PROPOGATING 

M HVCN 

D 1 (L, B 1) ,D2 (B2) 

^MOVE CHARACTERS NON-PROPOGATING LONG 

; MVCNL 

D1 {LR , B 1) , D 2 {B2) 

'/MOVE HALFWORDS 

«*MVH 

D1 ( El) , D2 (B2) 

Y -C MOVE REAL ADDRESS 

M VB A 

D 1 (B1) , D2 (B 2) 

✓MOVE TO BYTE IMMEDIATE 

HVBI 

D1(B1),12 

-'MOVE TO HALFWORD IMMEDIATE 

^MVHI 

D1(B1),12 

'/MULTIPLY ** 

H 

R 1, D2 {X2, B2) 

✓'MULTIPLY HALFWORDS ** 

•• MH 

D 1 ( B1) , D2 (B2) 

/MULTIPLY IMMEDIATE ** 

MI 

R1S,R1F,IH2 

/MULTIPLY REGISTER ** 

MR 

R 1, R2 

/.OR 

0 

R1 , D2(X2,B2) 

✓OR CHARACTERS 

OC 

D 1 (L,B 1) ,D2 (B2) 

v/OR CHARACTERS LONG 

i* OCL 

D1(LR,B 1) ,D2 (B2) 

'''OR IMMEDIATE 

01 

R1S,R1F,IH2 

v OR REGISTER 

OR 

R 1, R 2 
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SO 


$rm : 


pjt* 

$jcr 

YSV 


y 0R TO BYTE 1MM EDj 
-'SCAN LEFT EQUAL 


ATE 




* SCAN 
v SCAN 
v SCAN 


LEFT EQUAL LONG 
LEFT NOT EQUAL 
LEFT NOT EQUAL LONG 


OBI 

SLE 

SLEL 

SLNE 

SLNEL 


D 1 (B1) ,12 
D1 (L,B1) , D2 (B2) 

D 1 (LR , B 1) ,1)2 (B2) 
D 1 (L,B 1) , D2(B2> 

D1 (LR , B 1) , D2 ( B2) 


'/SCAN 1 

R IGHT 

EQUAL 

SRE 

D 1 (L,B 1) ,D2 {B2) 

v/ SCAN 

RIGHT 

EQUAL LONG 

SREL 

Dl (LR,B1) ,D2(B2) 

/SCAN 

RIGHT 

NOT EQUAL 

S RN E 

D1 (L,B 1) ,D2 (B2) 

v SCAN 

RIGHT 

NOT EQUAL LONG 

SRNEL 

Dl(LR,B 1) ,D2(B2) 

✓SCAN 

USING 

TABLE LEFT 

STL 

Dl (L, B 1) ,D2 (B2) 

/SCAN 

USING 

TABLE LEFT LONG 

STLL 

Dl {L R , B 1) , D2 (32) 

✓ SCAN 

USING 

TABLE RIGHT 

STR 

Dl (L, B1) , D2 (B2) 

SCAN 

USING 

TABLE RIGHT LONG 

STRL 

Dl (LR ,B 1) , D2 (B2) 

✓SHIFT 

LEFT 

ALGEBRAIC 

SLA 

R1,D2(B2) 

/SHIFT 

LEFT 

ALGEBRAIC IMMEDIATE 

S LAI 

R1,12 

/SHIFT 

LEFT 

DOUBLE ALGEBRAIC 

SLD A 

R 1, D2 (B2) 

✓SHIFT 

LEFT 

DOUBLE ALGEBRAIC IMMEDIATE 

SLDAI 

R 1,12 

✓SHIFT 

LEFT 

DOUBLE LOGICAL 

SL DL 

R 1 , D2 (B 2) 

/SHIFT 

LEFT 

DOUBLE LOGICAL IMMEDIATE 

SLDLI 

R 1,12 

/SHIFT 

LEFT 

LOGICAL 

SLL 

R1 ,D2 (B2) 

/SHIFT 

LEFT 

LOGICAL IMMEDIATE 

SLLI 

R 1,12 

✓SHIFT 

RIGHT ALGEBRAIC 

SR A 

R 1 , D2 (B2) 

/SHIFT 

RIGHT ALGEBRAIC IMMEDIATE 

SRAI 

R1 ,12 

✓SHIFT 

RIGHT DOUBLE ALGEBRAIC 

SRDA 

R1,D2(B2) 


1 


✓SHIFT RIGHT 
✓•SHIFT RIGHT 
'/SHIFT RIGHT 
/SHIFT RIGHT 
/SHIFT RIGHT 
✓'STORE 
/STORE 
-/STOR E 
/STORE 
/STORE 
r STORE 
I STORE 
STORE 
STORE 
STORE 
✓SUBTRACT 

✓ SUBTRACT 
✓SUBTRACT 
/SUBTRACT 
•'SUBTRACT 
/SUBTRACT 
v SUBTRACT 
- SUBTRACT 
✓SUBTRACT 

✓ SUBTRACT 

✓ SWAP 

/SWAP REGISTER 


DOUBLE ALGEBRAIC IMMEDIAT 
DOUBLE LOGICAL 
DOUBLE LOGICAL IMMEDIATE 
loGICAL 

LOGICAL IMMEDIATE 


BYTE 

DEFERRED IMMEDIATE 
DEFERRED REGISTER 
DEFERRED 

LEAST SIGNIFICANT PRODUCT 
MOST SIGNIFICANT PRODUCT 
MULTIPLE REAL ADDRESSES 
MULT. REAL ADDRESSES DEFERRED 
REAL ADDRESS 


ADDRESS 
FROM HALFWORD 
HALFWORDS 
HEX DIGIT 
IMMEDIATE 
LOGICAL 

LOGICAL IMMEDIATE 
LOGICAL REGISTER 
REGISTER 


IMMEDIATE 


SRDAI 

SR DL 

SRDLI 

SRL 

SR LI 

ST 

STB 

STDI 

STDR 

STD 

STLP 

STMP 

STMRA 

ST MRAD 

STRA 

S 

SA 

SHI 

SH 

SX 

SI 

SL 

SLI 

SLR 

SR 

SWP 

SW PR 


R1,12 
R 1, D2 (B 2) 

R1,12 
R 1 , D2 (B2) 

R 1,12 

R 1 , D2 (X 2, B2 ) 
R1,D2 (X2,B2) 

R 1F , IA 2 
R1 , R2 

R1,D2(X2,B2) 

R1 , D2 (X 2 , B2 ) 

R1,D2 (X2,B2) 
R1,R3,D2{B2) 
R1 , R3,D2 <B2) 

R1,D2(X 2,B2) 

R1,D2(X2,B2) 

R1,D2 (X2,B2) 

D1(B1),12 
D1 (Hi) , D2 (B2) 
R 1,12 

R1S , R1 F , IH2 
R1, D2(X2,B2) 
R1S,R1F,IH2 
R1 , R2 
R 1, R2 

R1,D2(X 2,B2) 

R1 , R2 
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✓ TEST 

AND 

BRANCH 

•'test 

AND 

BRANCH 

^ TEST 

AND 

BRANCH 

VTEST 

AND 

BRANCH 

^TEST 

AND 

BRANCH 

V TEST 

AND 

BRANCH 

^TEST 

AND 

BRANCH 

V 'TEST 

AND 

BRANCH 

✓ TEST 

AND 

BRANCH 

TEST 

AND 

BRANCH 

TEST 

AND 

BRANCH 

^TEST 

AND 

BRANCH 

v TEST 

UNDER MASK 

i/TEST 

UNDER MASK 

i/TEST 

UNDER MASK 

''TRANSLATE 

^TRANSLATE 

LONG 


MINUS 

MINUS REGISTER 
NOT MINUS 

NOT MINUS REGISTER 
NOT PLUS 

NOT PLUS REGISTER 
NOT ZERO 

NOT ZERO REGISTER 
PLUS 

PLUS REGISTER 
ZERO 

ZERO REGISTER 
BYTE IMMEDIATE 
IMMEDIATE 
REGISTER 


TBM 

TBMR 

TBNM 

TBNMK 

TBNP 

TBNPR 

TBNZ 

TBNZR 

TBP 

TBPR 

TBZ 

TBZR 

TMBI 

TMI 

TMR 

TR 

TRL 


R 

R 

R 

R 

R 

R 

R 

R 

R 

R 

R 

R 

D 

R 

R 

D 

D 


1, D2 

(X2) 

1 ,R2 


1, D2 

(X 2) 

1,R2 


1 ,D2 

(X2) 

1, R2 


1 , D2 

<X2) 

1 ,R2 


1,D2 

(X2) 

1 ,R2 


1, D2 

(X2) 

1 ,B2 


1 (B 1 

) ,12 

IF,I 

H2 


1 ,R2 

1 { L, B 1) , D2 {B2) 

1 (LR , B 1) ,D2 (B2) 


* L PA 


R1,N2,B2 loads the address of a parameter from the 


parameter list. 


N2 is the number beginning with zero of the 


parameter to be 


loaded, and B2 is 


the register that points to 


the parameter list. N2 
defaults to the standard 
macro. LM PA R1,R3,N2,B2 


defaults to the first parameter and B2 

l 

parameter register set up by the CALL 
may be used to load multiple parameter 


addresses. Starting with parameter N2, addresses are loaded 


into registers Hi through R3. 


** Multiply and divide are not implemented as described in 
the M4A Principles of Operations. Instead they were implemented 
using 360 conventions. For MUL1IPLY 

(opl+1) * (op2) the result is in (opl,opl + 1) 

and for DIVIDE 

(op 1, opl + 1) / (op2) the quotient is in (opl+1) and the 
remainder is in (opl). 
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2.2 RESTRICTIONS 


An 1CP application program must follow certain conventions 

in register usage. 

The 

ENTER macro 

generates the following 

register equates. 

MNEMONIC 360 

REG 

BUGS REG 

USE 

RW 

0 

13 

work register 

RP 

1 

2 

parameter register 

R2 

2 

2 

general 

• • • • 

• • 

• • • 


R12 1 

2 

12 

general 

unnamed 1 

4 

1 4 

link register 

unnamed 1 

5 

14 

entry register 

unnamed 1 

3 


base register 

unnamed 


0 

machine status register 

unnamed 


1 

PC and base register 

u nnamed 


15 

stack frame pointer 

RP and unnamed 

regist 

ers can not 

be referenced. 

R12 can not be 

refere 

need in a re 

-entrant routine. 

RW can not be 

used 

as an index 

or base register or as a 

length register in a 

" long 

" instruction. 

CLC (L) sets R 2 

if the 

compare is 

unsuccessful. 


CVB uses R2. 

CVD uses R2 and R3. 

SLE, SLEL, SLNE, SLNEL, SRE, SEEL, SRNE, SRNEL use R2. 
SRCll uses R2, R3, R4, and R5. 

STL, SI'LL, STR, STRL use R2 and R3. 

SVCD uses R2 and R3. 


SVCS uses R2. 


The 

follow 

ing BUGS 

instructions are 

not supported on the 

360: DEQ, 

ENQ, 

EXCC, LXB 

, LXBR, MV A, POPH 

, POPHL, 

POPM, PSHH, 

PSHHL, 

PSHM, 

RST, SD, 

h — 

SIO, SIOR, SRCH, 

SS, SVC, 

SVCD, SVCS, 


ioj<? 
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TRB, TSL, 

WST. 

Fixed 

BUGS 

procedures 

ca n 

use any 

BUGS 

instructions 

and 

fixed 

360 

proced ures 

can 

use any 

360 

instruction 

that 

does 

not co 

nflict. with 

any 

ICP insruction 


(i.e., LD is Load Deferred not floating point Load Long). 

2.3 PROCE DURE FORM AT 

ICP application procedures should have the following 
format: 

COPY OPS364A 
NAME ENTER 

<automatic variables> 

ENDAUTO 

• • • 

RETURN 

• • • 

PARMS (...) 

END 

The ENTER, ENDAUTO, RETURN, and PARMS macros ate described 
in the next section. 

2 j.4_SOME_USEFUL_ MACROS 

Procedures should be called using the CALL macro to 
generate the proper linkage between procedures. 

NAME CALL PROCEDURE ,<,{ ADDRESS_P A RAMETERS) <, V L>> 

< , MF= (E,PLIST) > 
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PROCEDURE is the name of the procedure to be called or a 
register specification, (R1) where R1 contains the address of 
the procedure. ADDRESS_PARAMETERS is a list of one or more 
addresses of parameters separated by commas. The address of a 
parameter can be given in a register. VL causes the high order 
bit of the last parameter address in the list to be set. PLIST 
is the address of tne parameter list. 

The parameter list can be generated by the list form of 
the CALL macro. 

NAME CALL ,(ADDRESS PARAMTERS)<,VL>,MF=L 

where NAME is the address of the parameter list. 

The ENTER macro defines a CSECT specified by name, saves 

o* t-v. f ."?• 

registers, and establishes a base register for addressing 
within the procedure. ENDAUTO indicates the end of any 
automatic storage. RETURN restores registers and returns to the 
calling procedure. Re-entrant subroutines should use RENTER, 
RENDAUTO, and RRETURN instead of ENTER, ENDAUTO, and RETURN. 

The FARMS macro must be included to give ICOPS necessary 
information about parameters. PARMS takes as operands a series 
of "declarations" describing the type, length, and access 
(read-only, read-write, or write-only) of each parameter being 
passed to the procedure. As an example, the statement 
PARMS (CL8 , : H, . H) 
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indicates that a procedure expects three parameters -- a 
character string of length eight which is read, but not 
modified; a halfword which is both read and modified; and a 
halfword which is only modified. 

The SELECT macro will generate a branch to an address 
selected by an index into a table of addresses. SELECT has the 
following format: 

NAME SELECT 1, A LI ST ,<REG-= SCRATCH , ORG= NO , I NC = N 1, 

HIGH=ERROR1,LOW=ERR0R2> 

I is either the address of a halfword index or a register 
specification, (81), where R1 is a register containing the 
index. If REG=SCRATCH, the index is computed in R1. ALIST is 
either the address of a list of addresses or a list of one or 
more addresses separated by commas and enclosed in parentheses. 
The index will begin at NO and be incremented by Nl. N1 must be 
1, 2, 4, or 8. NO defaults to 0, and Nl defaults to 1. if the 
index given is too small a branch is taken to ERROR1; if the 
index is too large a branch is taken to ERROR2. If ERROR1 or 
ERROR2 is omitted, the index is not checked for that illegal 
value. 
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3 GENERATION OF AN APPLICATION 


The 
be used 
v arious 
bet ween 
contains 


following describes the major CMS commands which should 
to generate the application system and maintain the 
system libraries. Figure 1 illustrates the relationship 
the commands and the files being manipulated. Section 4 
a complete list of these commands. 


3.1 OVERVIEW 

Starting with the SYSIN files, each procedure is assembled 
(using SREP) for either the local, remote, or both processors. 
After assembling the procedure, the SREP command adds the TEXT 
output of the mainframe or satellite assembler to the 
appropriate library -- LCLLIB TXTLIB, RMTLIB TXTLIB, or both. 
The filetype of the TEXT file is then altered to TEXTL or TEXTR 
in order to distinguish between the two object decks for 
icpable procedures. 


Once the two TXTLIBs have been created, new load modules 
are produced by running the SYSBLD command. SYSBLD first runs a 
link edit pre-processor, LEPRE, on the new libraries. Load 
modules for the local and/or remote processors are then built. 
For the 360, this is done with the CMS LOAD and GENMOD 
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commands; for BUGS, with the GMSLINK command. Note that icpable 
procedures on BUGS are loaded in separate segments so that they 
can be dynamically loaded and deleted from BUGS memory. The 
final step in the generation process is to ship the system 
MODU, the BUGS load module, to the satellite system. This is 
done with CHARON, a command which supports the transfer of 
files between the 360 and BUGS. 
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I-T 

| SXSIN | 
i_ 1 _j 


r-(- 

J I 

I SR 


1 I 

SREPL-J 

I-T I I 

| TEXTL 1-J | 

L- J , 


r-V- t 

I LCLLIB TXTLIB | 



LCLBLD S 


I 1 

l-SREPR 

I I r-1 

j l -q TEXTR | 


f RMTLIB TXTLIB ] 



BLD RMTBLD 


J 

I 



I 

j 


| system MODULE| 

i-j 


r—V-v —t 

|system MODU| 

T 

CHARON—(TO BUGS) 


Figure 1. The system Generation Process 


Ji.2_LE PRE 

LEPRE requires as input the two text libraries, RMTLIB and 
LCLLIB, and a data tile, LEPRE DATA, containing information 
about procedures in the application system. 

Each command in the LEPRE DATA file is of the form: 

keyword (machname) namel name2 • • • nameN 
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•keyword' identifies the command type and can take on the 
following values and meanings: 

LIBRARY - 'namel' through 'nameN* specify CMS text 
libraries in which are to be found the object 
modules to be located on *machname'. 

FIXED - 'namel' through 'nameN' are the names of modules 
to be permanently fixed on 'machname'. 

ICPABLE - The following names are of modules which may be 
moved from one processor to the other. They are 
to be initially located on 'machname'. 

RICPABLE - This has the same meaning as ICPABLE, except 
the modules named are specified to be 
"reusable". 1 

DEFAULT - This command specifies that any modules not 
explicitly located by the user are to default to 
be fixed on 'machname'. 

'machname' for this implementation is either '360* or 'BUGS' 
and takes on the meanings noted above. 


l By reusable, we mean that the static environment of the 
procedure is completely reinitialized whenever the procedure is 
entered. For a non-reusable procedure, the static environment 
on entry is the same as it was left following the last call of 
the procedure. 
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As an example of the above, the following commands would 
produce the allocation - A FIXED on the 360, B ICPABLE and 
initially on the 360, and C and D FIXED on BUGS: 

DEFAULT (360) 

LIBRARY (360) LCLLIB 
LIBRARY (BUGS) RMTLIB 
FIXED (360) A 
ICPABLE (360) B 
FIXED (BUGS) C D 

After reading and processing the command file, LEPRE builds two 
text libraries, LWCB and RWCB, which contain procedure tables 
and control blocks needed by ICOPS. 

Note that LEPRE reverses the names of the text decks of 
all procedures in the text libraries (i.e., a text deck named 
GENERATE would become ETARENEG). 

3^3_DEBUGGING_AND_REBUILDING 

Standard debugging techniques can be used on an ICOPS 
application system. Load modules can be patched and procedures 
can be patched or reassembled. 

When debugging an ICOPS application, remember that the 
names of all procedures have been changed. The reverse name 
must be given when using NEWBUG, FUDD, or MODZAP. 
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Procedures 

are 

reassembled 

u 

sing the 

appropriate SREP. 

(See SREP exec 

in Section 4) 

Not 

e that th 

e reverse 

na me i s 

included as a 

SREP 

parameter 

si 

nee that 

text deck 

must be 

deleted from the 

text 

library. 






A text deck can be split from either library, and 
corrected by adding REP cards or by ZAPping the text file. It 
can then be replaced in the text library. Remember to split and 
replace the reverse named text file in both libraries. 

If REP cards are added to local procedures, just do a 
local build, LCLBLD. If REP cards are added to remote 
procedures, do a remote build, RMTBLD, and then CHARON the new 
HODU to BUGS. If both remote and local procedures are changed, 
then rebuild the entire system with SYSBLD. 

When rebuilding the application system, it is necessary to 
rerun LEPRE and PT if a change is made to the parameters 
expected by a procedure or if LEPRE DATA has been changed. If a 
procedure has been reassembled and no parameters are changed, 
run LEPRE without PT. 
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4 GENERATION EXEC S 

The following is a list of the various EXECs used to build an 
application system. Optional parameters are indicated by < . .. >. 

SYS BLD SYSTEM <NOLEPRE> <NOPT> 

This exec builds the entire application system. SYSTEM 
is the entry point on the 360 of the system and will be 


the name 

of the 

mod ule 

file. LEPRE 

will be ru 

n and 

Procedure 

Tables 

will be 

asse mbled 

unless othe 

rwise 


specified. 

LCLBLD SYSTEM <PT> 

This exec builds the 360 module. SYSTEM is the entry 
point on the 360 of the system and will be the name of 
the module file. A local Procedure Table will be 
assembled only if specified. 

RMTBLD SYSTEM <PT> 

This exec builds the BUGS module. SYSTEM will be the 
name of the BUGS modu file. A remote Procedure Table 
will be assembled only if specified. 

SREP FILENAME EMANELIF [L or R or I] MACLIB 
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This exec assembles the procedure specified by FILENAME 
for either the 360 or BUGS or both. MACLIB is the name 
of the application system macro library. 

ASML FILENAME MACLIB <assembly parameters> 

This exec assembles a 360 procedure specified by 

FILENAME. MACLIB is the name of the system macro 

library. 

ASM R FILFNAME MACLIB <assembly parameters> 

This exec assembles a BUGS procedure specified by 

FILENAME. MACLIB is the name of the system macro 

library. 

TXT! FILENAME 

This exec replaces the text deck specified by FILENAME 
in the LCLLIB TXTLIB and alters the file type of the 
text deck to TEXTL. 


TXT R FILENAME 

This exec replaces the text deck specified by FILENAME 
in the RMTLIB TXTLIB and alters the file type of the 
text deck to TEXTR. 


-18- 



ICOPS Application Development Manual 


5 T HE rCOPS_MONITOR JL _HERMES 


One of the major design goals of ICOPS was to allow the user 
to dynaroi ca lly examine, evaluate, and modify the manner in which 
he has divided the tasks in his application between the mainframe 
and satellite processors. To this end, designed into ICOPS is a 
terminal-oriented command language with which the user can perform 
these functions. The following paragraphs describe how the command 
language monitor is entered and what facilities are available to 
the user. 

5. 1_.ENTERING THE MONITOR 

The design of the command language monitor is such as to 
make it "invisible" to user programs, that is, user programs do 
not have to be written with cognizance of the monitor. User 
programs may, if they wish, invoke the monitor directly by a 
simple CALL to the appropriate entry point. More often it is 
expected that the user will wish to enter the monitor at times 
which are not necessarily synchronized with his program’s 
execution. Therefore, asynchronous entry conditions are defined 
wnich cause the monitor to be entered. 
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On the 360, the monitor is entered when the user's virtual 
CMS machine receives an external interrupt. Normally, when CMS 
receives an external interrupt, it enters the DEBUG 
environment. The ICOPS initialization routine, however, usurps 
this function and enters instead the ICOPS command language 
environment. 

On BUGS, the satellite system, the relationship of the 
monitor to the operating system almost exactly parallels the 
360 situation. The action causing entry to the monitor is a 
panel interrupt, an interrupt analogous to the 360's external 
interrupt. Normally, this interrupt is undefined (i.e., there 
is no system routine to handle it) . The BUGS operating system 
therefore enters the satellite debugging environment. When 
ICOPS is run, the initialization routine defines the command 
language monitor as the routine to handle panel interrupts, and 
the monitor is thereafter entered on any panel interrupt. 

5.2 THE ICOPS COMMAND LANGUAGE 


The following lists all commands currently supported by 
the monitor. Some commands are, as noted, specific to one 
system or the other. In the command descriptions, underlining 
indicates the shortest abbreviation recognized by the monitor. 
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An OH bar (|) between parameters indicates a choice is to be 
made between the parameters. 

BUGS 

| BUGS cmndline | 

The BUGS command provides an interface between the satellite 
monitor and the BUGS operating system. The 'cmndline 1 as typed 
by the user is passed on to the operating system just as if it 
had been entered in the normal BUGS command environment. This 
allows the user to temporarily suspend execution of his 
application and execute operating system functions (e.g., file 
erasure, file listing, etc.). 

CMS 

r-1 

I CMS cmndline ) 

i-j 

The CMS command is the 360 equivalent to the BUGS command -- 
the 'cmndline' is passed on to the CMS command handler. 

CP 

r-1 

| CP cmndline j 

The CP command functions as the BUGS and CMS commands, except 
that the 'cmndline' is passed to CP. 
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debug 

1-T 

| DEBUG | 

t-j 

The DEBUG command provides an interface between the ICOPS 
command language monitor and the debugging environment on the 
local machine (i.e., the machine on which the DEBUG command was 
entered) . 

disk 

--t 

I DISK filename | 

j 

It was anticipated that the user of ICOPS would fairly 
frequently want to enter a prespecified set of commands each 
time he ran his application. The DISK command allows him to 
create a file whose name is ’filename* (on either machine) and 
then request ICOPS execution of each command in the file. 

EXTERNAL 

r-1 

| EXTERNAL | 

L-J 

This command "gives back" to the user the use of the external 
and panel interrupts which were usurped by the ICOPS monitor. 
After the monitor is entered, execution of the EXTERNAL command 
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cause the local debugging environment to be entered just 
as if the monitor were not in control. 

10 LOG 

J IOLOG ON]OFF|PRINT ] 

L- j 

The 10L0G command is used to turn on, turn off, or print the 
current statistics on I/O activity across the 
mainframe/sateHite link. The statistics kept on the link are 
the total number of READS and WRITES issued and the total 
amount of data transfer in each direction. 

ITRACE 

] ITRACE ON|0FF ] 

L-J 

ITRACE (for Internal trace) is a command allowing the ICOPS 
designers to trace the execution of a preselected set of ICOPS 
system modules. Included in the trace are the names of the 
called and calling programs together with a selected set of 
pertinent parameter addresses. 
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LOCAL PROCS 

i-1 

I LCL I 

L _I 

The LOCAL command requests a display o£ the names of all 
procedures which are currently on the local processor. The 
monitor responds with such a list of names. 

LOCATION 

i-1 

1 LOCATION procname | 

L-J 

The LOCATION command is used tc determine the current location 
of the procedure named ’procname’. The monitor responds with 
either "LOCAL" or "REMOTE" depending on the location of the 
proced ure. 

MOVE 

i-1 

I MOVE procname 1 

L-J 

The MOVE command is used to move a procedure from one processor 
to the other. The direction of tranfer is implicit in the 
current location of the procedure. Note that the actual 
procedure movement does not occur until the first time the 
procedure is called after the move reguest is issued. When the 
procedure is moved, a message is printed on the user’s terminal 
giving the new location of the procedure. 
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PRINT STATISTICS TABLE 

| PST procname | 

i_i 

This command is used to display on the user’s terminal the 
current statistics for 'procname'. The monitor responds with a 
display of the current statistics which tiie user previously 
specified for collection. 

PRINT PROCEDURE TABLE ENT£X 

r -! 

| PTE procname | 

The PTE command displays the current status of the PTE for the 
procedure 'procname'. The ccmmand is mainly for use t>y the 
ICOPS system designers. 


REMOTE 

r-1 

I R MT j 

The REMOTE command is completely analogous to the LOCAL 
command. The result is a list of all ICPable procedures 
currently on the remote processor. 
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STATISTICS 


| STAT procname|ALL ON|OFF OPT= o STATS= s FILE= f | 


The STATISTICS command controls the taking of statistics for a 
particular procedure (•procname') or all ICPanle procedures 
(ALL). The three possible functions are to initiate or 
terminate (ON or OFF) statistics collection. When statistics 
collection is initiated, the OPT and STATS keywords control 
what statistics are taken and where they are displayed. The OPT 
keyword is a string composed of any or all of the following 
letters: 

S Gather statistics for this procedure. (If 'S' is not 
specified, only procedure calls and returns will be 
traced.) 

M Gather statistics on procedure movement. 

D Write statistics records to 'a disk file. 

T Write statistics records to the terminal. 


The STATS keyword specifies what statistics are to be kept 
and is a string composed of any or all of the following: 

C Trace the name of the calling procedure. 

D Trace dedicated I/O operations (disk and tape) performed 
by the procedure. 

L Trace I/O activity across the mainframe/satellite link 
caused by the procedure. 
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P Trace the number of page reads incurred by the procedure 
(360 side only) . 

T Trace the elapsed real ("clock") time spent while in the 
procedure. 

U Trace the number of unit-record I/O operations (card 
reader, card punch, printer) performed by the procedure. 

V Trace the elapsed virtual CPU time spent in the 

procedure. (The virtual CPU time is equal to the real 

time minus time spent waiting for paging operations, CP 
overhead, etc.) 

$ Trace the cost of each call of the procedure (according 
to the accounting system of the processor on which the 
procedure is running). 

The ' file=' option specifies the name of the CMS disk file 
where the statistics will be written. The filetype is always 
TRACE. 

Default values are OPT= ST STATS= CDLPTUV$ F1L E = ICPTRACE. 

| STAT LOG FILE = fname | 

The LOG command writes a statistics record to disk, 
option specifies the name of the CMS disk file. The 
TRACE and the default filename is ICPTRACE. 


The *file= ' 
filetype is 
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WART CONTROL BLOCK 

I WCB procname | 

I_J N 

The WCB command displays the current status o£ 
•procname*. This command is for use by the 
designers. 


the procedure 
ICOPS system 
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